DVARIANT Class

The DVARIANT class implements a VARIANT data type. The variant data type is a tagged union that can be used to represent any other data type. While lacking in efficiency, they are heavily used in COM Automation for its flexibility. The main purpose of the DVARIANT class is to make its use as easy as possible when you need to use them to work with COM Automation objects.

Include file: DVARIANT.INC.

Helper Procedures

Constructors

Creates an instance of the DVARIANT class.

CONSTRUCTOR
CONSTRUCTOR (BYREF dv AS DVARIANT)
CONSTRUCTOR (BYVAL v AS VARIANT)
CONSTRUCTOR (BYVAL pwsz AS WSTRING PTR)
CONSTRUCTOR (BYREF dws AS DWSTRING)
CONSTRUCTOR (BYREF bs AS BSTRING)
CONSTRUCTOR (BYVAL pvar AS VARIANT PTR)
CONSTRUCTOR (BYVAL cy AS CURRENCY)
CONSTRUCTOR (BYVAL dec AS DECIMAL)
DECLARE CONSTRUCTOR (BYVAL _value AS LONG)
CONSTRUCTOR (BYREF pDisp AS IDispatch PTR, BYVAL fAddRef AS BOOLEAN = FALSE)
CONSTRUCTOR (BYREF pUnk AS IUnknown PTR, BYVAL fAddRef AS BOOLEAN = FALSE)
CONSTRUCTOR (BYVAL _value AS LONGINT, BYVAL _vType AS WORD = VT_I4)
CONSTRUCTOR (BYVAL _value AS DOUBLE, BYVAL _vType AS WORD = VT_R8)
CONSTRUCTOR (BYVAL _value AS LONGINT, BYREF strType AS STRING)
CONSTRUCTOR (BYVAL _value AS DOUBLE, BYREF strType AS STRING)
CONSTRUCTOR (BYVAL _pvar AS ANY PTR, BYVAL _vType AS WORD)
CONSTRUCTOR (BYVAL _pvar AS ANY PTR, BYREF strType AS STRING)

Examples

DIM dv AS DVARIANT = "Test string"   ' Creates a VT_BSTR (8) variant
DIM dv AS DVARIANT = 12345           ' Creates a VT_I4 (3) variant
DIM dv AS DVARIANT = 123456.78       ' Creates a VT_R8 (5) variant

We can use the constructors to pass values to parameters in procedures without assigning them first to a variable, e.g.:

SUB Foo (BYREF dv AS DVARIANT)
   PRINT dv
END SUB

Foo "Test string"
Foo 12345
Foo DVARIANT(12345, "LONG")

SUB Foo (BYVAL dv AS DVARIANT PTR)
   PRINT AfxDVarToStr(dv)
END SUB
Foo @DVARIANT("Test string")
Foo @DVARIANT(12345)
Foo @DVARIANT(12345, "LONG")```

SUB Foo (BYVAL v AS VARIANT)
   PRINT AfxVarToStr(v)
END SUB

Foo DVARIANT("Test string")
Foo DVARIANT(12345)
Foo DVARIANT(12345, "LONG")

SUB Foo (BYVAL v AS VARIANT PTR)
   PRINT AfxVarToStr(v)
END SUB
Foo DVARIANT("Test string")
Foo DVARIANT(12345)
Foo DVARIANT(12345, "LONG")

Operators

Procedures that perform a certain function with their operands. They do the same actions that the native FreeBasic operators but with variants. For detailed descriptions see the FreeBasic documentation.

Global Operators

OPERATOR & (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS DVARIANT
OPERATOR * (BYREF dv AS DVARIANT) AS VARIANT PTR

Cast Operators

OPERATOR Cast () AS VARIANT
OPERATOR Cast () AS VARIANT PTR
OPERATOR CAST () BYREF AS WSTRING

Assignment operators

OPERATOR Let (BYREF dv AS DVARIANT)
OPERATOR Let (BYVAL v AS VARIANT)
OPERATOR Let (BYVAL pvar AS VARIANT PTR)
OPERATOR LET (BYVAL pwszStr AS WSTRING PTR)
OPERATOR Let (BYVAL cy AS CURRENCY)
OPERATOR Let (BYVAL dec AS DECIMAL)
OPERATOR Let (BYREF bs AS BSTRING)
OPERATOR Let (BYREF dws AS DWSTRING)
DECLARE OPERATOR LET (BYVAL _value AS LONG)
OPERATOR Let (BYREF pDisp AS IDispatch PTR)
OPERATOR Let (BYREF pUnk AS IUnknown PTR)
OPERATOR Let (BYVAL _value AS LONGINT)
OPERATOR Let (BYVAL _value AS DOUBLE)
OPERATOR += (BYREF dv AS DVARIANT)
OPERATOR -= (BYREF dv AS DVARIANT)
OPERATOR *= (BYREF dv AS DVARIANT)
OPERATOR /= (BYREF dv AS DVARIANT)
OPERATOR \= (BYREF dv AS DVARIANT)
OPERATOR Mod= (BYREF dv AS DVARIANT)
OPERATOR Imp= (BYREF dv AS DVARIANT)
OPERATOR Eqv= (BYREF dv AS DVARIANT)
OPERATOR ^= (BYREF dv AS DVARIANT)

Arithmetic operators

OPERATOR + (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS DVARIANT
OPERATOR - (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS DVARIANT
OPERATOR * (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS DVARIANT
OPERATOR / (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS DVARIANT
OPERATOR \ (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS DVARIANT
OPERATOR ^ (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS DOUBLE
OPERATOR Mod (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS INTEGER
OPERATOR - (BYREF dv AS DVARIANT) AS DVARIANT

Relational operators

OPERATOR = (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS BOOLEAN
OPERATOR <> (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS BOOLEAN
OPERATOR < (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS BOOLEAN
OPERATOR > (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS BOOLEAN
OPERATOR <= (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS BOOLEAN
OPERATOR >= (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS BOOLEAN

Bitwise operators

OPERATOR And (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS INTEGER
OPERATOR Eqv (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS INTEGER
OPERATOR Imp (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS INTEGER
OPERATOR Not (BYREF dv AS DVARIANT) AS INTEGER
OPERATOR Or (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS INTEGER
OPERATOR Xor (BYREF dv1 AS DVARIANT, BYREF dv2 AS DVARIANT) AS INTEGER

SUB Foo (BYVAL v AS VARIANT)
   PRINT AfxVarToStr(@v)
END SUB
DIM dv AS DVARIANT = "Test string"
Foo dv

Using the pointer syntax:

SUB Foo (BYVAL v AS VARIANT)
   PRINT AfxVarToStr(@v)
END SUB
DIM pdv AS DVARIANT PTR  = NEW DVARIANT("Test string")
Foo *pdv
Delete pdv

Using the constructors

SUB Foo (BYVAL v AS VARIANT)
   PRINT AfxVarToStr(@v)
END SUB
Foo DVARIANT(12345, "LONG")

Note to the CAST operator

The CAST operators allow to transparently pass the underlying VARIANT to a procedure. They aren’t called directly.

SUB Foo (BYREF v AS VARIANT)
   PRINT AfxVarToStr(@v)
END SUB
Foo DVARIANT(12345, "LONG")

SUB Foo2 (BYVAL v AS VARIANT)
   PRINT AfxVarToStr(@v)
END SUB
Foo2 DVARIANT(12345, "LONG")

SUB Foo3 (BYREF dv AS DVARIANT)
   PRINT dv
END SUB
Foo3 DVARIANT(12345, "LONG")

SUB Foo4 (BYVAL dv AS DVARIANT PTR)
   PRINT AfxDVarToStr(dv)
END SUB
Foo4 @DVARIANT(12345, "LONG")

Remarks

I haven’t added a cast to return a numeric value because with procedures like PRINT that can use both a number or a string the compiler will fail, not knowing which cast it should use. If you want to convert it to a number, use VAL(DVARIANT).

vType

Returns the VARIANT type.

FUNCTION vType () AS VARTYPE

The following table shows the available data types and where these values can be used.

Attach

Attaches a variant to the class.

FUNCTION Attach (BYVAL pvar AS VARIANT PTR) AS HRESULT
FUNCTION Attach (BYREF v AS VARIANT) AS HRESULT

Remark

Marks the source variant as VT_EMPTY instead of clearing it with VariantClear because we aren’t making a duplicate of the contents, but transferring ownership.

Return value

Returns S_OK (0) on success or an HRESULT error code on failure.

Detach

Detaches the variant data from this class and transfers ownership to the passed variant.

FUNCTION Detach (BYVAL pvar AS VARIANT PTR) AS HRESULT
FUNCTION Detach (BYREF v AS VARIANT) AS HRESULT

Remark

This method transfers ownership of the underlying variant and marks it as empty.

Return value

Returns S_OK (0) or an HRESULT error code.

ChangeType

Converts the variant from one type to another.

FUNCTION ChangeType (BYVAL vtNew AS VARTYPE, BYVAL wFlags AS USHORT = 0) AS HRESULT

Return value

Returns S_OK (0) or an HRESULT error code.

ChangeTypeEx

Converts the variant from one type to another.

FUNCTION ChangeTypeEx (BYVAL vtNew AS VARTYPE, BYVAL lcid AS LCID = 0, BYVAL wFlags AS USHORT = 0) AS HRESULT

Return value

Returns S_OK (0) or an HRESULT error code.

GetDim

Gets the number of dimensions in the array.

FUNCTION GetDim () AS ULONG

Return value

Returns the number of dimensions for variants of type VT_ARRAY; returns 0 otherwise.

GetLBound

Gets the lower bound for the specified dimension of the safe array.

FUNCTION GetLBound (BYVAL nDim AS UINT = 1) AS LONG

Return value

Returns the lower bound for the specified dimension of the safe array for variants of type VT_ARRAY; returns 0 otherwise.

GetUBound

Gets the upper bound for the specified dimension of the safe array.

FUNCTION GetUBound (BYVAL nDim AS UINT = 1) AS LONG

Return value

Returns the upper bound for the specified dimension of the safe array for variants of type VT_ARRAY; returns 0 otherwise.

GetElementCount

Gets the number of elements in the array.

FUNCTION GetElementCount () AS ULONG

Return value

Returns the number of elements for variants of type VT_ARRAY; returns 1 otherwise.

DecToCY

Converts a DVARIANT of type decimal to a CY structure.

FUNCTION DecToCY () AS CY

Return value

Returns the contents of a VT_DECIMAL variant as a CY structure.

DecToDouble

Converts a DVARIANT of type decimal to a double.

FUNCTION DecToDouble () AS DOUBLE

Return value

Returns the contents of a VT_DECIMAL variant as a DOUBLE.

Round

Rounds a variant to the specified number of decimal places.

FUNCTION Round (BYREF dv AS DVARIANT, BYVAL cDecimals AS LONG) AS DVARIANT

Return value

A DVARIANT containing the rounded result.

FormatNumber

Formats a DVARIANT containing numbers into a string form.

FUNCTION FormatNumber (BYVAL iNumDig AS LONG = -1, BYVAL ilncLead AS LONG = -2, _
   BYVAL iUseParens AS LONG = -2, BYVAL iGroup AS LONG = -2, BYVAL dwFlags AS DWORD = 0) AS DWSTRING

Return value

A DWSTRING containing the formatted value.

Remarks

This function uses the user’s default locale while calling VarTokenizeFormatString and VarFormatFromTokens.

GetBooleanElement

Extracts a single boolean element from a safe array of booleans.

FUNCTION GetBooleanElement (BYVAL iElem AS ULONG) AS BOOLEAN

Return value

The retrieved value.

GetDoubleElement

Extracts a single DOUBLE element from a safe array of doubles.

FUNCTION GetDoubleElement (BYVAL iElem AS ULONG) AS DOUBLE

Return value

The retrieved value.

GetLongElement

Extracts a single LONG element from a safe array of longs.

FUNCTION GetLongElement (BYVAL iElem AS ULONG) AS LONG

Return value

The retrieved value.

GetLongIntElement

Extracts a single LONGINT element from a safe array of long integers.

FUNCTION GetLongIntElement (BYVAL iElem AS ULONG) AS LONGINT

Return value

The retrieved value.

GetShortElement

Extracts a single SHORT element from a safe array of short integers.

FUNCTION GetShortElement (BYVAL iElem AS ULONG) AS SHORT

Return value

The retrieved value.

GetStringElement

Extracts a single BSTR element from a safe array of unicode strings.

FUNCTION GetStringElement (BYVAL iElem AS ULONG) AS BSTR

Return value

The retrieved value.

GetULongElement

Extracts a single ULONG element from a safe array of unsigned longs.

FUNCTION GetULongElement (BYVAL iElem AS ULONG) AS ULONG

Return value

The retrieved value.

GetULongIntElement

Extracts a single ULONGINT element from a safe array of unsigned long integers.

FUNCTION GetULongIntElement (BYVAL iElem AS ULONG) AS ULONGINT

Return value

The retrieved value.

GetUShortElement

Extracts a single USHORT element from a safe array of unsigned shorts.

FUNCTION GetUShortElement (BYVAL iElem AS ULONG) AS USHORT

Return value

The retrieved value.

GetVariantElement

Extracts a single Variant element from a safe array of variants.

FUNCTION GetVariantElement (BYVAL iElem AS ULONG) AS DVARIANT

Return value

The retrieved value.

Put

Assigns values to a DVARIANT.

SUB Put (BYREF wsz AS WSTRING)
SUB Put (BYREF dws AS DWSTRING)
SUB Put (BYREF bs AS BSTRING)
FUNCTION Put (BYREF dv AS DVARIANT) AS HRESULT
FUNCTION Put (BYVAL v AS VARIANT) AS HRESULT
FUNCTION Put (BYVAL pvar AS VARIANT PTR) AS HRESULT
FUNCTION Put (BYREF pDisp AS IDispatch PTR, BYVAL fAddRef AS BOOLEAN = FALSE) AS HRESULT
FUNCTION Put (BYREF pUnk AS IUnknown PTR, BYVAL fAddRef AS BOOLEAN = FALSE) AS HRESULT
SUB Put (BYVAL _value AS LONGINT, BYVAL _vType AS WORD = VT_I4)
SUB Put (BYVAL _value AS DOUBLE, BYVAL _vType AS WORD = VT_R8)
SUB Put (BYVAL _value AS LONGINT, BYREF strType AS STRING)
SUB Put (BYVAL _value AS DOUBLE, BYREF strType AS STRING)
SUB Put (BYVAL _pv AS ANY PTR, BYVAL _vType AS WORD)
SUB Put (BYVAL _pv AS ANY PTR, BYREF strType AS STRING)

PutNull

Assigns a null value to the DVARIANT.

SUB PutNull

PutBool

Assigns a boolean value to the DVARIANT.

SUB PutBool (BYVAL _value AS BOOL)

PutBoolean

Assigns a boolean value to the DVARIANT.

SUB PutBoolean (BYVAL _value AS BOOLEAN)

PutByte

Assigns a byte value to the DVARIANT.

SUB PutByte (BYVAL _value AS BYTE)

PutUByte

Assigns an unsigned ubyte value to the DVARIANT.

SUB PutUByte (BYVAL _value AS UBYTE)

PutShort

Assigns a short integer value to the DVARIANT.

SUB PutShort (BYVAL _value AS SHORT)

PutUShort

Assigns an unsigned short integer value to the DVARIANT.

SUB PutUShort (BYVAL _value AS USHORT)

PutInt

Assigns an INT_ (long) value to the DVARIANT.

SUB PutInt (BYVAL _value AS INT_)

Remark

Don’t confuse an INT_ (LONG) with the Free Basic INTEGER data type.

PutUInt

Assigns an UINT (unsigned long) value to the DVARIANT.

SUB PutUInt (BYVAL _value AS UINT)

Remark

Don’t confuse an UINT (ULONG) with the Free Basic UINTEGER data type.

PutLong

Assigns a LONG value to the DVARIANT.

SUB PutLong (BYVAL _value AS LONG)

PutULong

Assigns a ULONG value to the DVARIANT.

SUB PutULong (BYVAL _value AS ULONG)

PutLongInt

Assigns a LONGINT value to the DVARIANT.

SUB PutULong (BYVAL _value AS LONGINT)

PutULongInt

Assigns a ULONGINT value to the DVARIANT.

SUB PutULongInt (BYVAL _value AS ULONGINT)

PutSingle

Assigns a SINGLE value to the DVARIANT.

SUB PutSingle (BYVAL _value AS SINGLE)

PutFloat

Assigns a SINGLE value to the DVARIANT.

SUB PutFloat (BYVAL _value AS SINGLE)

PutDouble

Assigns a DOUBLE value to the DVARIANT.

SUB PutDouble (BYVAL _value AS DOUBLE)

PutBooleanArray

Initializes DVARIANT from an array of Boolean values.

FUNCTION PutBooleanArray (BYVAL prgf AS WINBOOL PTR, BYVAL cElems AS ULONG) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_BOOL variant.

PutShortArray

Initializes DVARIANT from an array of signed 16-bit integer values.

FUNCTION PutShortArray (BYVAL prgf AS SHORT PTR, BYVAL cElems AS ULONG) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_I2 variant.

PutUshortArray

Initializes DVARIANT from an array of 16-bit unsigned integer values.

FUNCTION PutUshortArray (BYVAL prgf AS USHORT PTR, BYVAL cElems AS ULONG) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_UI2 variant.

PutLongArray

Initializes DVARIANT from an array of signed 32-bit integer values.

FUNCTION PutLongArray (BYVAL prgf AS LONG PTR, BYVAL cElems AS ULONG) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_I4 variant.

PutULongArray

Initializes DVARIANT from an array of 32-bit unsigned integer values.

FUNCTION PutULongArray (BYVAL prgf AS ULONG PTR, BYVAL cElems AS ULONG) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_UI4 variant.

PutLongIntArray

Initializes DVARIANT from an array of signed 64-bit integer values.

FUNCTION PutLongIntArray (BYVAL prgf AS LONGINT PTR, BYVAL cElems AS ULONG) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_I8 variant.

PutULongIntArray

Initializes DVARIANT from an array of unsigned 64-bit integer values.

FUNCTION PutULongIntArray (BYVAL prgf AS ULONGINT PTR, BYVAL cElems AS ULONG) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_UI8 variant.

PutDoubleArray

Initializes DVARIANT from an array of unsigned 64-bit integer values.

FUNCTION PutDoubleArray (BYVAL prgf AS DOUBLE PTR, BYVAL cElems AS ULONG) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_R8 variant.

PutStringArray

Initializes DVARIANT from an array of unicode strings.

FUNCTION PutStringArray (BYVAL prgsz AS PDWSTRING, BYVAL cElems AS ULONG) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_BSTR variant.

PutBuffer

Initializes DVARIANT with the contents of a buffer.

FUNCTION PutBuffer (BYVAL pv AS VOID PTR, BYVAL cb AS UINT) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_UI1 variant.

Example

DIM dv AS DVARIANT
DIM strIn AS STRING = "Test string"
dv.PutBuffer(STRPTR(strIn), LEN(strIn))

DIM nBytes AS LONG = dv.GetElementCount
DIM strOut AS STRING = SPACE(nBytes)
dv.ToBuffer(STRPTR(strOut), nBytes)
PRINT strOut

PutDateString

Initializes DVARIANT VT_DATE from a string.

FUNCTION PutDateString (BYVAL pwszDate AS WSTRING PTR, BYVAL lcid AS LCID = 0, _
   BYVAL dwFlags AS ULONG = 0) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_DATE variant.

PutDec

Initializes DVARIANT with the contents of a DECIMAL structure.

FUNCTION PutDec (BYCAL dec AS DECIMAL) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_DECIMAL OR VT_BYREF variant.

PutDecFromCY

Converts a currency value to a variant of type VT_DECIMAL.

FUNCTION PutDecFromCY (BYVAL cyIn AS CY) AS HRESULT

Return value

This function can return one of these values.

Remarks

Creates a VT_DECIMAL variant.

PutDecFromDouble

Converts a double value to a variant of type VT_DECIMAL.

FUNCTION PutDecFromDouble (BYVAL dbIn AS DOUBLE) AS HRESULT

Return value

This function can return one of these values.

Remarks

Creates a VT_DECIMAL variant.

PutDecFromStr

Initializes DVARIANT as VT_DECIMAL from a string.

FUNCTION PutDecFromStr (BYVAL pwszIn AS WSTRING PTR, BYVAL lcid AS LCID = 0, _
   BYVAL dwFlags AS ULONG = 0) AS HRESULT

Return value

This function can return one of these values.

Remarks

Creates a VT_DECIMAL variant.

PutFileTime

Initializes DVARIANT with the contents of a FILETIME structure.

FUNCTION PutFileTime (BYVAL pft AS FILETIME PTR) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_DATE variant.

PutFileTimeArray

Initializes DVARIANT with an array of FILETIME structures.

FUNCTION PutFileTimeArray (BYVAL prgft AS FILETIME PTR, BYVAL cElems AS ULONG) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_DATE variant.

PutGuid

Initializes DVARIANT from a GUID.

FUNCTION PutGuid (BYVAL rguid AS GUID PTR) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY OR VT_UI1 variant.

PutPropVariant

Initializes DVARIANT from the contents of a PROPVARIANT structure.

FUNCTION PutPropVariant (BYVAL pPropVar AS PROPVARIANT PTR) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Normally, the data stored in the PROPVARIANT is copied to the VARIANT without a datatype change. However, in the following cases, there is no direct VARIANT support for the datatype, and they are converted as shown.

VT_BLOB, VT_STREAM
Converted to VT_UNKNOWN. The punkVal member will contain a pointer to an IStream that contains the source data.

VT_LPSTR, VT_LPWSTR, VT_CLSID
Converted to VT_BSTR,

VT_FILETIME
Converted to VT_DATE.

VT_VECTOR OR x
Converted to VT_ARRAY OR x

The following types cannot be converted with this function.

VT_STORAGE
VT_BLOB_OBJECT
VT_STREAMED_OBJECT
VT_STORED_OBJECT
VT_CF
VT_VECTOR OR VT_CF

PutRecord

Initializes DVARIANT with a reference to an UDT.

FUNCTION PutRecord (BYVAL pIRecordInfo AS IRecordInfo PTR, BYVAL pRec AS VOID PTR) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_RECORD variant.

PutRef

Assigns a value by reference (a pointer to a variable).

FUNCTION PutRef (BYVAL _pvar AS ANY PTR, BYVAL _vType AS WORD) AS HRESULT
FUNCTION PutRef (BYVAL _pvar AS ANY PTR, BYREF strType AS STRING) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_BYREF variant of the sepecified type.

PutResource

Initializes the DVARIANT based on a string resource imbedded in an executable file.

FUNCTION PutResource (BYVAL hinst AS HINSTANCE, BYVAL id AS UINT) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_BSTR variant. If the resource does not exist, this function initializes the VARIANT as VT_EMPTY and returns a failure code.

PutSafeArray

Initializes DVARIANT from a safe array.

FUNCTION PutSafeArray (BYVAL parray AS SAFEARRAY PTR) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_ARRAY variant.

PutStrRet

Initializes DVARIANT with the string stored in a STRRET structure.

FUNCTION PutStrRet (BYVAL pstrret AS STRRET PTR, BYVAL pidl AS PCUITEMID_CHILD) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_BSTR variant. This function frees the resources used for the STRRET contents.

PutSystemTime

Initializes DVARIANT with the contents of a SYSTEMTIME structure.

FUNCTION PutSystemTime (BYVAL pst AS SYSTEMTIME PTR) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_DATE variant.

PutUtf8

Initializes DVARIANT with the contents of an UTF-8 string.

FUNCTION PutUtf8 (BYREF strUtf8 AS STRING) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_BSTR variant.

PutVariantArrayElement

Initializes DVARIANT with a value stored in another VARIANT structure.

FUNCTION PutVariantArrayElement (BYVAL pvarIn AS VARIANT PTR, BYVAL iElem AS ULONG) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

This helper function works for VARIANT structures of the following types:

VT_BSTR
VT_BOOL
VT_I2
VT_I4
VT_I8
VT_U12
VT_U14
VT_U18
VT_DATE
VT_ARRAY | (any one of VT_BSTR, VT_BOOL, VT_I2, VT_I4, VT_I8, VT_U12, VT_U14, VT_U18, VT_DATE)

Additional types may be supported in the future.

This function extracts a single value from the source VARIANT structure and uses that value to initialize the output VARIANT structure. The calling application must use VariantClear to free the VARIANT referred to by pvar when it is no longer needed.

If the source VARIANT is an array, iElem must be less than the number of elements in the array.

If the source VARIANT has a single value, iElem must be 0.

If the source VARIANT is empty, this function always returns an error code.

You can use GetElementCount to obtain the number of elements in the array or array.

PutVbDate

Initializes DVARIANT with the contents of a DATE value.

FUNCTION PutVbDate (BYREF vbDate AS DATE_) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

Creates a VT_DATE variant.

ToBooleanArray

Extracts an array of boolean values from DVARIANT.

FUNCTION ToBooleanArray (BYVAL prgf AS WINBOOL PTR, BYVAL crgn AS ULONG) AS ULONG

Return value

The count of WINBOOL elements extracted from the DVARIANT.

Remarks

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of boolean values.

If the source VARIANT is of type VT_ARRAY OR VT_BOOL, this function extracts up to crgn WINBOOL values and places them into the buffer pointed to by prgf. If the VARIANT contains more elements than will fit into the prgf buffer, this function returns 0.

ToBooleanArrayAlloc

Extracts an array of boolean values from DVARIANT.

FUNCTION ToBooleanArrayAlloc (BYVAL pprgf AS WINBOOL PTR PTR) AS ULONG

Return value

The count of WINBOOL elements extracted from the DVARIANT.

Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of WINBOOL values.

If DVARIANT is of type VT_ARRAY OR VT_BOOL, this function extracts an array of WINBOOL values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgf when it is no longer needed.

ToBstr

Extracts the content of the underlying variant and returns it as a BSTRING.

FUNCTION ToBstr () AS BSTRING

Return value

The contents of the variant as a BSTRING.

Example

DIM dv AS DVARIANT = "Test string"
DIM bs AS BSTRING = dv.ToBstr

ToBuffer

Extracts the contents of a DVARIANT of type VT_ARRRAY OR VT_UI1 to a buffer.

FUNCTION ToBuffer (BYVAL pv AS VOID PTR, BYVAL cb AS UINT) AS HRESULT

Return value

Returns one of the following values:

Remarks

This function is used when the calling application expects a VARIANT to hold a buffer value. The calling application should check that the value has the expected length before it calls this function.

If DVARIANT has type VT_ARRAY OR VT_UI1, this function extracts the first cb bytes from the structure and places them in the buffer pointed to by pv.

If the stored value has fewer than cb bytes, then function fails and the buffer is not modified.

If the value has more than cb bytes, then function succeeds and truncates the value.

To retrieve the size of the array call GetElementCount.

Example

DIM dv AS DVARIANT
DIM strIn AS STRING = "Test string"
dv.PutBuffer(STRPTR(strIn), LEN(strIn))

DIM nBytes AS LONG = dv.GetElementCount
DIM strOut AS STRING = SPACE(nBytes)
dv.ToBuffer(STRPTR(strOut), nBytes)
PRINT strOut

ToBuffer (STRING)

Extracts the contents of a DVARIANT of type VT_ARRRAY OR VT_UI1 to a string used as a buffer.

FUNCTION ToBuffer () AS STRING

Return value

A string with the contents of the array.

ToDosDateTime

Extracts a date and time value in Microsoft MS-DOS format from a DVARIANT of type VT_DATE.

FUNCTION ToDosDateTime (BYVAL pwDate AS USHORT PTR, BYVAL pwTime AS USHORT PTR) AS HRESULT

Return value

If this function succeeds, it returns S_OK (0). Otherwise, it returns an HRESULT error code.

Remarks

This helper function is used when the calling application expects a DVARIANT to hold a datetime value.

If DVARIANT is of type VT_DATE, this function extracts the datetime value.

If DVARIANT is not of type VT_DATE, the function attempts to convert the value in the VARIANT structure into the right format. If a conversion is not possible, it returns a failure code.

ToDoubleArray

Extracts an array of DOUBLE values from DVARIANT.

FUNCTION ToDoubleArray (BYVAL prgn AS DOUBLE PTR, BYVAL crgn AS ULONG) AS ULONG

Return value

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of DOUBLE values.

If the source VARIANT is of type VT_ARRAY OR VT_R8, this function extracts up to crgn DOUBLE values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

ToDoubleArrayAlloc

Extracts an array of DOUBLE values from DVARIANT.

FUNCTION ToDoubleArrayAlloc (BYVAL pprgn AS ULONGINT PTR PTR) AS ULONG

Return value

The count of DOUBLE elements extracted from the DVARIANT.

Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of DOUBLE values.

If DVARIANT is of type VT_ARRAY OR VT_R8, this function extracts an array of DOUBLE values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer neede

ToFileTime

Returns the contents of a DVARIANT of type VT_DATE as a FILETIME structure.

FUNCTION ToFileTime (BYVAL stfOut AS AFX_PSTIME_FLAGS) AS FILETIME

Return value

A FILETIME structure.

ToGuid

Returns the contents of a DVARIANT containing a GUID string as a GUID structure.

FUNCTION ToGuid () AS GUID

Return value

Returns the contents of a DVARIANT containing a GUID string as an unicode GUID string.

ToGuidBStr

Returns the contents of a DVARIANT containing a GUID string as an unicode GUID string.

FUNCTION ToGuidBStr () AS BSTRING

Return value

A GUID string.

ToGuidStr

Returns the contents of a DVARIANT containing a GUID string as an unicode GUID string.

FUNCTION ToGuidStr () AS DWSTRING

Return value

A GUID string.

ToGuidWStr

Returns the contents of a DVARIANT containing a GUID string as an unicode GUID string.

FUNCTION ToGuidWStr () AS DWSTRING

Return value

A GUID string.

ToLongArray

Extracts an array of LONG values from DVARIANT.

FUNCTION ToLongArray (BYVAL prgn AS LONG PTR, BYVAL crgn AS ULONG) AS ULONG

Return value

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of Int32 values.

If the source VARIANT is of type VT_ARRAY OR VT_I4, this function extracts up to crgn Int32 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

ToLongArrayAlloc

Extracts an array of LONG values from DVARIANT.

FUNCTION ToLongArrayAlloc (BYVAL pprgn AS LONG PTR PTR) AS ULONG

Return value

The count of LONG elements extracted from the DVARIANT.

Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of LONG values.

If DVARIANT is of type VT_ARRAY OR VT_I4, this function extracts an array of LONG values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

ToLongIntArray

Extracts an array of LONGINT values from DVARIANT.

FUNCTION ToLongIntArray (BYVAL prgn AS LONGINT PTR, BYVAL crgn AS ULONG) AS ULONG

Return value

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of Int64 values.

If the source VARIANT is of type VT_ARRAY OR VT_UI4, this function extracts up to crgn Int64 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

ToLongIntArrayAlloc

Extracts an array of LONGINT values from DVARIANT.

FUNCTION ToLongIntArrayAlloc (BYVAL pprgn AS LONGINT PTR PTR) AS ULONG

Return value

The count of LONGINT elements extracted from the DVARIANT.

Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of LONGINT values.

If DVARIANT is of type VT_ARRAY OR VT_I8, this function extracts an array of LONGINT values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

ToShortArray

Extracts an array of Int16 values from DVARIANT.

FUNCTION ToShortArray (BYVAL prgn AS SHORT PTR, BYVAL crgn AS ULONG) AS ULONG

Return value

The count of Int16 elements extracted from the DVARIANT.

Remarks

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of Int16 values.

If the source VARIANT is of type VT_ARRAY OR VT_I2, this function extracts up to crgn Int16 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

ToShortArrayAlloc

Extracts an array of SHORT values from DVARIANT.

FUNCTION ToShortArrayAlloc (BYVAL pprgn AS SHORT PTR PTR) AS ULONG

Return value

The count of SHORT elements extracted from the DVARIANT.

Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of SHORT values.

If DVARIANT is of type VT_ARRAY OR VT_I2, this function extracts an array of SHORT values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

ToStr

Extracts the content of the underlying variant and returns it as a DWSTRING.

FUNCTION ToStr () AS DWSTRING

Return value

The contents of the variant as a DWSTRING.

Example

DIM dv AS DVARIANT = "Test string"
DIM dws AS DWSTRING = dv.ToStr

ToStringArray

Extracts data from a vector structure into a PWSTR array.

FUNCTION ToStringArray (BYVAL prgsz AS PWSTR, BYVAL crgsz AS ULONG) AS ULONG

Return value

The count of PWSTR elements extracted from the DVARIANT.

Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of PWSTR values. If the VARIANT contains more elements than will fit into the prgsz buffer, this function returns 0.

ToStringArrayAlloc

Extracts an array of PWSTR values from DVARIANT.

FUNCTION ToStringArrayAlloc (BYVAL pprgsz AS PWSTR PTR) AS ULONG

Return value

The count of PWSTR elements extracted from the DVARIANT.

Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of PWSTR values.

This function extracts an array of PWSTR values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to free the memory used by each of the strings and to release the array pointed to by pprgn when it is no longer needed.

ToStrRet

Returns the contents of a DVARIANT of type VT_BSTR to a STRRET stucture.

FUNCTION ToStrRet () AS STRRET

Return value

A STRRET structure.

ToSystemTime

Returns the contents of DVARIANT of type VT_DATE as a FILETIME structure.

FUNCTION ToSystemTime () AS SYSTEMTIME

Return value

A SYSTEMTIME structure.

ToULongArray

Extracts an array of ULONG values from DVARIANT.

FUNCTION ToULongArray (BYVAL prgn AS ULONG PTR, BYVAL crgn AS ULONG) AS ULONG

Return value

The count of UInt32 elements extracted from the DVARIANT.

Remarks

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of UInt32 values.

If the source VARIANT is of type VT_ARRAY OR VT_UI4, this function extracts up to crgn UInt32 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

ToULongArrayAlloc

Extracts an array of ULONG values from DVARIANT.

FUNCTION ToULongArrayAlloc (BYVAL pprgn AS ULONG PTR PTR) AS ULONG

Return value

The count of ULONG elements extracted from the DVARIANT.

Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of ULONG values.

If DVARIANT is of type VT_ARRAY OR VT_UI4, this function extracts an array of ULONG values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

ToULongIntArray

Extracts an array of ULONGINT values from DVARIANT.

FUNCTION ToULongIntArray (BYVAL prgn AS ULONGINT PTR, BYVAL crgn AS ULONG) AS ULONG

Return value

The count of UInt64 elements extracted from the DVARIANT.

Remarks

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of UInt64 values.

If the source VARIANT is of type VT_ARRAY OR VT_UI8, this function extracts up to crgn UInt64 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

ToULongIntArrayAlloc

Extracts an array of ULONGINT values from DVARIANT.

FUNCTION ToULongIntArrayAlloc (BYVAL pprgn AS ULONGINT PTR PTR) AS ULONG

Return value

The count of ULONGINT elements extracted from the DVARIANT.

Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of ULONGINT values.

If DVARIANT is of type VT_ARRAY OR VT_UI8, this function extracts an array of ULONGINT values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

ToUShortArray

Extracts an array of UInt16 values from DVARIANT.

FUNCTION ToUShortArray (BYVAL prgn AS USHORT PTR, BYVAL crgn AS ULONG) AS ULONG

Return value

The count of UInt16 elements extracted from the DVARIANT.

Remarks

This helper function is used when the calling application expects a VARIANT to hold an array that consists of a fixed number of UInt16 values.

If the source VARIANT is of type VT_ARRAY OR VT_I2, this function extracts up to crgn UInt16 values and places them into the buffer pointed to by prgn. If the VARIANT contains more elements than will fit into the prgn buffer, this function returns 0.

ToUShortArrayAlloc

Extracts an array of USHORT values from DVARIANT.

FUNCTION ToUShortArrayAlloc (BYVAL pprgn AS USHORT PTR PTR) AS ULONG

Return value

The count of USHORT elements extracted from the DVARIANT.

Remarks

This helper function is used when the calling application expects a DVARIANT to hold an array of USHORT values.

If DVARIANT is of type VT_ARRAY OR VT_UI2, this function extracts an array of SHORT values into a newly allocated array. The calling application is responsible for using CoTaskMemFree to release the array pointed to by pprgn when it is no longer needed.

ToUtf8

Returns the contents of a DVARIANT containing a BSTR as an UTF-8 encoded string.

FUNCTION ToUtf8 () AS STRING

Return value

The UTF-8 string.

ToVbDate

Returns the contents of a DVARIANT of type VT_DATE as a DATE value.

FUNCTION ToVbDate () AS DATE_

Return value

A DATE_ value (double).

AfxDVarToStr

Extracts the contents of a DVARIANT to a DWSTRING.

FUNCTION AfxDVarToStr (BYREF dv AS DVARIANT) AS DWSTRING

AfxDVarToStr

Extracts the contents of a DVARIANT to a DWSTRING.

FUNCTION AfxDVarToStr (BYVAL pdv AS DVARIANT PTR) AS DWSTRING
#define DVAR_TOSTR(dv) AfxDVarToStr(dv)

AfxDVarToBuffer

Extracts the contents of a variant that contains an array of bytes.

FUNCTION AfxDVarToBuffer (BYREF cvIn AS DVARIANT, BYVAL pv AS LPVOID, BYVAL cb AS ULONG) AS HRESULT

Return value

Returns one of the following values:

AfxDVarOptPrm

Returns a DVARIANT suitable to be used with optional parameters.

FUNCTION AfxDVarOptPrm () AS DVARIANT
#define DVAR_OPTPRM AfxDVarOptPrm

Remarks

If you want to call a method that has optional variant parameters, you still have to pass the parameters, but in a way that the methods know that they were omitted. Specifically, you have to pass them as type VT_ERROR, code DISP_E_PARAM_NOT_FOUND.

DIM v AS VARIANT = TYPE(VT_ERROR, 0, 0, 0, DISP_E_PARAMNOTFOUND)